home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Resources / Sound / AHI / Developer / docs / ahi.doc < prev    next >
Text File  |  1997-11-04  |  65KB  |  2,024 lines
  1. TABLE OF CONTENTS
  2. 0001 ahi.device/--background--
  3. 0002 ahi.device/AHI_AllocAudioA
  4. 0003 ahi.device/AHI_AllocAudioRequestA
  5. 0004 ahi.device/AHI_AudioRequestA
  6. 0005 ahi.device/AHI_BestAudioIDA
  7. 0006 ahi.device/AHI_ControlAudioA
  8. 0007 ahi.device/AHI_FreeAudio
  9. 0008 ahi.device/AHI_FreeAudioRequest
  10. 0009 ahi.device/AHI_GetAudioAttrsA
  11. 0010 ahi.device/AHI_LoadSound
  12. 0011 ahi.device/AHI_NextAudioID
  13. 0012 ahi.device/AHI_PlayA
  14. 0013 ahi.device/AHI_SampleFrameSize
  15. 0014 ahi.device/AHI_SetEffect
  16. 0015 ahi.device/AHI_SetFreq
  17. 0016 ahi.device/AHI_SetSound
  18. 0017 ahi.device/AHI_SetVol
  19. 0018 ahi.device/AHI_UnloadSound
  20. 0019 ahi.device/CMD_FLUSH
  21. 0020 ahi.device/CMD_READ
  22. 0021 ahi.device/CMD_RESET
  23. 0022 ahi.device/CMD_START
  24. 0023 ahi.device/CMD_STOP
  25. 0024 ahi.device/CMD_WRITE
  26. 0025 ahi.device/CloseDevice
  27. 0026 ahi.device/NSCMD_DEVICEQUERY
  28. 0027 ahi.device/OpenDevice
  29. ahi.device/--background--
  30.  
  31. PURPOSE
  32.  
  33.        The 'ahi.device' was first created because the lack of standards
  34.        when it comes to sound cards on the Amiga. Another reason was to
  35.        make it easier to write multi-channel music programs.
  36.  
  37.        This device is by no means the final and perfect solution. But
  38.        hopefully, it can evolve into something useful until AT brings you
  39.        The Real Thing (TM).
  40.  
  41.  
  42. OVERVIEW
  43.  
  44.        Please see the document "AHI Developer's Guide" for more
  45.        information.
  46.  
  47.  
  48.        * Driver based
  49.  
  50.        Each supported sound card is controlled by a library-based audio
  51.        driver. For a 'dumb' sound card, a new driver could be written in
  52.        a few hours. For a 'smart' sound card, it is possible to utilize an
  53.        on-board DSP, for example, to maximize performance and sound quality.
  54.        For sound cards with own DSP but little or no memory, it is possible
  55.        to use the main CPU to mix channels and do the post-processing
  56.        with the DSP. Drivers are available for most popular sound cards,
  57.        as well as an 8SVX (mono) and AIFF/AIFC (mono & stereo) sample render
  58.        driver.
  59.   
  60.        * Fast, powerful mixing routines (yeah, right... haha)
  61.   
  62.        The device's mixing routines mix 8- or 16-bit signed samples, both
  63.        mono and stereo, located in Fast-RAM and outputs 16-bit mono or stereo
  64.        (with stereo panning if desired) data, using any number of channels
  65.        (as long as 'any' means less than 128).  Tables can be used speed
  66.        the mixing up (especially when using 8-bit samples).  The samples can
  67.        have any length (including odd) and can have any number of loops.
  68.        There are also so-called HiFi mixing routines that can be used, that
  69.        use linear interpolation and gives 32 bit output.
  70.        
  71.        * Support for non-realtime mixing
  72.   
  73.        By providing a timing feature, it is possible to create high-
  74.        quality output even if the processing power is lacking, by saving
  75.        the output to disk, for example as an IFF AIFF or 8SXV file.
  76.   
  77.        * Audio database
  78.   
  79.        Uses ID codes, much like Screenmode IDs, to select the many
  80.        parameters that can be set. The functions to access the audio
  81.        database are not too different from those in 'graphics.library'.
  82.        The device also features a requester to get an ID code from the
  83.        user.
  84.   
  85.        * Both high- and low-level protocol
  86.   
  87.        By acting both like a device and a library, AHI gives the programmer
  88.        a choice between full control and simplicity. The device API allows
  89.        several programs to use the audio hardware at the same time, and
  90.        the AUDIO: dos-device driver makes playing and recording sound very
  91.        simple for both the programmer and user.
  92.   
  93.        * Future Compatible
  94.   
  95.        When AmigaOS gets device-independent audio worth it's name, it should
  96.        not be too difficult to write a driver for AHI, allowing applications
  97.        using 'ahi.device' to automatically use the new OS interface. At
  98.        least I hope it wont.
  99.  
  100.  
  101.  
  102. ahi.device/AHI_AllocAudioA
  103.  
  104. NAME
  105.        AHI_AllocAudioA -- allocates and initializes the audio hardware
  106.        AHI_AllocAudio -- varargs stub for AHI_AllocAudioA()
  107.  
  108.  
  109. SYNOPSIS
  110.        audioctrl = AHI_AllocAudioA( tags );
  111.        D0                           A1
  112.  
  113.        struct AHIAudioCtrl *AHI_AllocAudioA( struct TagItem * );
  114.  
  115.        audioctrl = AHI_AllocAudio( tag1, ... );
  116.  
  117.        struct AHIAudioCtrl *AHI_AllocAudio( Tag, ... );
  118.  
  119.  
  120. FUNCTION
  121.        Allocates and initializes the audio hardware, selects the best
  122.        mixing routine (if necessary) according to the supplied tags.
  123.        To start playing you first need to call AHI_ControlAudioA().
  124.  
  125.  
  126. INPUTS
  127.        tags - A pointer to a tag list.
  128.  
  129.  
  130. TAGS
  131.  
  132.        AHIA_AudioID (ULONG) - The audio mode to use. Default is
  133.            AHI_DEFAULT_ID. (AHI_DEFAULT_ID is the ID the user has selected
  134.            in the preferences program. It's a good value to use the first
  135.            time she starts your application.)
  136.  
  137.        AHIA_MixFreq (ULONG) - Desired mixing frequency. The actual
  138.            mixing rate may or may not be exactly what you asked for.
  139.            Default is AHI_DEFAULT_FREQ. (AHI_DEFAULT_FREQ is the user's
  140.            prefered frequency.)
  141.  
  142.        AHIA_Channels (UWORD) - Number of channel to use. The actual
  143.            number of channels used will be equal or grater than the
  144.            requested. If too many channels were requested, this function
  145.            will fail. This tag must be supplied.
  146.  
  147.        AHIA_Sounds (UWORD) - Number of sounds to use. This tag must be
  148.            supplied.
  149.  
  150.        AHIA_SoundFunc (struct Hook *) - A function to call each time
  151.            when a sound has been started. The function receives the
  152.            following parameters:
  153.                A0 - (struct Hook *)
  154.                A2 - (struct AHIAudioCtrl *)
  155.                A1 - (struct AHISoundMessage *)
  156.            The hook may be called from an interrupt, so normal interrupt
  157.            restrictions apply.
  158.  
  159.            The called function should follow normal register conventions,
  160.            which means that d2-d7 and a2-a6 must be preserved.
  161.  
  162.            Default is NULL.
  163.  
  164.        AHIA_PlayerFunc (struct Hook *) - A function to be called at regular
  165.            intervals. By using this hook there is no need for music players
  166.            to use other timing, such as VBLANK or CIA timers. But the real
  167.            reason it's present is that it makes it possible to do non-
  168.            realtime mixing to disk.
  169.  
  170.            Using this interrupt source is currently the only supported way
  171.            to ensure that no mixing occurs between calls to AHI_SetVol(),
  172.            AHI_SetFreq() or AHI_SetSound().
  173.  
  174.            If the sound playback is done without mixing, 'realtime.library'
  175.            is used to provide timing. The function receives the following
  176.            parameters:
  177.                A0 - (struct Hook *)
  178.                A2 - (struct AHIAudioCtrl *)
  179.                A1 - Undefined.
  180.            Do not assume A1 contains any particular value!
  181.            The hook may be called from an interrupt, so normal interrupt
  182.            restrictions apply.
  183.  
  184.            The called function should follow normal register conventions,
  185.            which means that d2-d7 and a2-a6 must be preserved.
  186.  
  187.            Default is NULL.
  188.  
  189.        AHIA_PlayerFreq (Fixed) - If non-zero, enables timing and specifies
  190.            how many times per second PlayerFunc will be called. This must
  191.            be specified if AHIA_PlayerFunc is! Do not use any extreme
  192.            frequencies. The result of MixFreq/PlayerFreq must fit an UWORD,
  193.            ie it must be less or equal to 65535. It is also suggested that
  194.            you keep the result over 80. For normal use this should not be a
  195.            problem. Note that the data type is Fixed, not integer. 50 Hz is
  196.            50<<16.
  197.  
  198.            Default is a reasonable value. Don't depend on it.
  199.  
  200.        AHIA_MinPlayerFreq (Fixed) - The minimum frequency (AHIA_PlayerFreq)
  201.            you will use. You MUST supply this if you are using the device's
  202.            interrupt feature!
  203.  
  204.        AHIA_MaxPlayerFreq (Fixed) - The maximum frequency (AHIA_PlayerFreq)
  205.            you will use. You MUST supply this if you are using the device's
  206.            interrupt feature!
  207.  
  208.        AHIA_RecordFunc (struct Hook *) - This function will be called
  209.            regularly when sampling is turned on (see AHI_ControlAudioA())
  210.            with the following parameters:
  211.                A0 - (struct Hook *)
  212.                A2 - (struct AHIAudioCtrl *)
  213.                A1 - (struct AHIRecordMessage *)
  214.            The message (AHIRecordMessage) is filled as follows:
  215.                ahirm_Buffer - Pointer to the samples. The buffer is valid
  216.                    until next time the Hook is called.
  217.                ahirm_Length - Number of sample FRAMES in buffer.
  218.                    To get the size in bytes, multiply by 4 if ahiim_Type is
  219.                    AHIST_S16S.
  220.                ahirm_Type - Always AHIST_S16S at the moment, but you *must*
  221.                    check this, since it may change in the future!
  222.            The hook may be called from an interrupt, so normal interrupt
  223.            restrictions apply. Signal a process if you wish to save the
  224.            buffer to disk. The called function should follow normal register
  225.            conventions, which means that d2-d7 and a2-a6 must be preserved.
  226.  
  227.            NOTE: The function MUST return NULL (in d0). This was previously
  228.            not documented. Now you know.
  229.  
  230.            Default is NULL.
  231.  
  232.        AHIA_UserData (APTR) - Can be used to initialize the ahiac_UserData
  233.            field. Default is 0.
  234.  
  235.  
  236. RESULT
  237.        A pointer to an AHIAudioCtrl structure or NULL if an error occured.
  238.  
  239.  
  240. EXAMPLE
  241.  
  242.  
  243. NOTES
  244.        SoundFunc will be called in the same manner as Paula interrupts
  245.        occur; when the device has updated its internal variables and can
  246.        accept new commands.
  247.  
  248.  
  249. BUGS
  250.  
  251.  
  252. SEE ALSO
  253.        AHI_FreeAudio(), AHI_ControlAudioA()
  254.  
  255.  
  256. ahi.device/AHI_AllocAudioRequestA
  257.  
  258. NAME
  259.        AHI_AllocAudioRequestA -- allocate an audio mode requester.
  260.        AHI_AllocAudioRequest -- varargs stub for AHI_AllocAudioRequestA()
  261.  
  262.  
  263. SYNOPSIS
  264.        requester = AHI_AllocAudioRequestA( tags );
  265.        D0                                  A0
  266.  
  267.        struct AHIAudioModeRequester *AHI_AllocAudioRequestA(
  268.            struct TagItem * );
  269.  
  270.        requester = AHI_AllocAudioRequest( tag1, ... );
  271.  
  272.        struct AHIAudioModeRequester *AHI_AllocAudioRequest( Tag, ... );
  273.  
  274.  
  275. FUNCTION
  276.        Allocates an audio mode requester data structure.
  277.  
  278.  
  279. INPUTS
  280.        tags - A pointer to an optional tag list specifying how to initialize
  281.            the data structure returned by this function. See the
  282.            documentation for AHI_AudioRequestA() for an explanation of how
  283.            to use the currently defined tags.
  284.  
  285.  
  286. RESULT
  287.        requester - An initialized requester data structure, or NULL on
  288.            failure. 
  289.  
  290.  
  291. EXAMPLE
  292.  
  293.  
  294. NOTES
  295.        The requester data structure is READ-ONLY and can only be modified
  296.        by using tags!
  297.  
  298.  
  299. BUGS
  300.  
  301.  
  302. SEE ALSO
  303.       AHI_AudioRequestA(), AHI_FreeAudioRequest()
  304.  
  305.  
  306. ahi.device/AHI_AudioRequestA
  307.  
  308. NAME
  309.        AHI_AudioRequestA -- get an audio mode from user using an requester.
  310.        AHI_AudioRequest -- varargs stub for AHI_AudioRequestA()
  311.  
  312.  
  313. SYNOPSIS
  314.        success = AHI_AudioRequestA( requester, tags );
  315.        D0                           A0         A1
  316.  
  317.        BOOL AHI_AudioRequestA( struct AHIAudioModeRequester *,
  318.            struct TagItem * );
  319.  
  320.        result = AHI_AudioRequest( requester, tag1, ... );
  321.  
  322.        BOOL AHI_AudioRequest( struct AHIAudioModeRequester *, Tag, ... );
  323.  
  324.  
  325. FUNCTION
  326.        Prompts the user for an audio mode, based on the modifying tags.
  327.        If the user cancels or the system aborts the request, FALSE is
  328.        returned, otherwise the requester's data structure reflects the
  329.        user input.
  330.  
  331.        Note that tag values stay in effect for each use of the requester
  332.        until they are cleared or modified by passing the same tag with a
  333.        new value.
  334.  
  335.  
  336. INPUTS
  337.        requester - Requester structure allocated with
  338.            AHI_AllocAudioRequestA(). If this parameter is NULL, this
  339.            function will always return FALSE with a dos.library/IoErr()
  340.            result of ERROR_NO_FREE_STORE.
  341.        tags - Pointer to an optional tag list which may be used to control
  342.            features of the requester.
  343.  
  344.  
  345. TAGS
  346.        Tags used for the requester (they look remarkable similar to the
  347.        screen mode requester in ASL, don't they? ;-) )
  348.  
  349.        AHIR_Window (struct Window *) - Parent window of requester. If no
  350.            AHIR_Screen tag is specified, the window structure is used to
  351.            determine on which screen to open the requesting window.
  352.  
  353.        AHIR_PubScreenName (STRPTR) - Name of a public screen to open on.
  354.            This overrides the screen used by AHIR_Window.
  355.  
  356.        AHIR_Screen (struct Screen *) - Screen on which to open the
  357.            requester. This overrides the screen used by AHIR_Window or by
  358.            AHIR_PubScreenName.
  359.  
  360.        AHIR_PrivateIDCMP (BOOL) - When set to TRUE, this tells AHI to
  361.            allocate a new IDCMP port for the requesting window. If not
  362.            specified or set to FALSE, and if AHIR_Window is provided, the
  363.            requesting window will share AHIR_Window's IDCMP port.
  364.  
  365.        AHIR_IntuiMsgFunc (struct Hook *) - A function to call whenever an
  366.            unknown Intuition message arrives at the message port being used
  367.            by the requesting window. The function receives the following
  368.            parameters:
  369.                A0 - (struct Hook *)
  370.                A1 - (struct IntuiMessage *)
  371.                A2 - (struct AHIAudioModeRequester *)
  372.  
  373.        AHIR_SleepWindow (BOOL) - When set to TRUE, this tag will cause the
  374.            window specified by AHIR_Window to be "put to sleep". That is, a
  375.            busy pointer will be displayed in the parent window, and no
  376.            gadget or menu activity will be allowed. This is done by opening
  377.            an invisible Intuition Requester in the parent window.
  378.  
  379.        AHIR_UserData (APTR) - A 32-bit value that is simply copied in the
  380.            ahiam_UserData field of the requester structure.
  381.  
  382.        AHIR_TextAttr (struct TextAttr *) - Font to be used for the
  383.            requesting window's gadgets and menus. If this tag is not
  384.            provided or its value is NULL, the default font of the screen
  385.            on which the requesting window opens will be used. This font
  386.            must already be in memory as AHI calls OpenFont() and not
  387.            OpenDiskFont().
  388.  
  389.        AHIR_Locale (struct Locale *) - Locale to use for the requesting
  390.            window. This determines the language used for the requester's
  391.            gadgets and menus. If this tag is not provided or its value is
  392.            NULL, the system's current default locale will be used.
  393.  
  394.        AHIR_TitleText (STRPTR) - Title to use for the requesting window.
  395.            Default is no title.
  396.  
  397.        AHIR_PositiveText (STRPTR) - Label of the positive gadget in the
  398.            requester. English default is "OK".
  399.  
  400.        AHIR_NegativeText (STRPTR) - Label of the negative gadget in the
  401.            requester. English default is "Cancel".
  402.  
  403.        AHIR_InitialLeftEdge (WORD) - Suggested left edge of requesting
  404.            window.
  405.  
  406.        AHIR_InitialTopEdge (WORD) - Suggested top edge of requesting
  407.            window.
  408.  
  409.        AHIR_InitialWidth (WORD) - Suggested width of requesting window.
  410.  
  411.        AHIR_InitialHeight (WORD) - Suggested height of requesting window.
  412.  
  413.        AHIR_InitialAudioID (ULONG) - Initial setting of the Mode list view
  414.            gadget (ahiam_AudioID). Default is ~0 (AHI_INVALID_ID), which
  415.            means that no mode will be selected.
  416.  
  417.        AHIR_InitialMixFreq (ULONG) - Initial setting of the frequency
  418.            slider. Default is the lowest frequency supported.
  419.  
  420.        AHIR_InitialInfoOpened (BOOL) - Whether to open the property
  421.            information window automatically. Default is FALSE.
  422.  
  423.        AHIR_InitialInfoLeftEdge (WORD) - Initial left edge of information
  424.            window.
  425.  
  426.        AHIR_InitialInfoTopEdge (WORD) - Initial top edge of information
  427.            window.
  428.  
  429.        AHIR_DoMixFreq (BOOL) - Set this tag to TRUE to cause the requester
  430.            to display the frequency slider gadget. Default is FALSE.
  431.  
  432.        AHIR_DoDefaultMode (BOOL) - Set this tag to TRUE to let the user
  433.            select the mode she has set in the preferences program. If she
  434.            selects this mode,  ahiam_AudioID will be AHI_DEFAULT_ID and
  435.            ahiam_MixFreq will be AHI_DEFAULT_FREQ. Note that if you filter
  436.            the mode list (see below), you must also check the mode (with
  437.            AHI_BestAudioIDA()) before you use it since the user may change 
  438.            the meaning of AHI_DEFAULT_MODE anytime, without your knowledge.
  439.            Default is FALSE. (V4)
  440.  
  441.        AHIR_FilterFunc (struct Hook *) - A function to call for each mode
  442.            encountered. If the function returns TRUE, the mode is included
  443.            in the file list, otherwise it is rejected and not displayed. The
  444.            function receives the following parameters:
  445.                A0 - (struct Hook *)
  446.                A1 - (ULONG) mode id
  447.                A2 - (struct AHIAudioModeRequester *)
  448.  
  449.        AHIR_FilterTags (struct TagItem *) - A pointer to a tag list used to
  450.            filter modes away, like AHIR_FilterFunc does. The tags are the
  451.            same as AHI_BestAudioIDA() takes as arguments. See that function
  452.            for an explanation of each tag.
  453.  
  454.  
  455. RESULT
  456.        result - FALSE if the user cancelled the requester or if something
  457.            prevented the requester from opening. If TRUE, values in the
  458.            requester structure will be set.
  459.  
  460.            If the return value is FALSE, you can look at the result from the
  461.            dos.library/IoErr() function to determine whether the requester
  462.            was cancelled or simply failed to open. If dos.library/IoErr()
  463.            returns 0, then the requester was cancelled, any other value
  464.            indicates a failure to open. Current possible failure codes are
  465.            ERROR_NO_FREE_STORE which indicates there was not enough memory,
  466.            and ERROR_NO_MORE_ENTRIES which indicates no modes were available
  467.            (usually because the application filter hook filtered them all
  468.            away).
  469.  
  470.  
  471. EXAMPLE
  472.  
  473.  
  474. NOTES
  475.        The requester data structure is READ-ONLY and can only be modified
  476.        by using tags!
  477.  
  478.        The mixing/recording frequencies that are presented to the user
  479.        may not be the only ones a driver supports, but just a selection.
  480.  
  481.  
  482. BUGS
  483.  
  484.  
  485. SEE ALSO
  486.       AHI_AllocAudioRequestA(), AHI_FreeAudioRequest()
  487.  
  488.  
  489. ahi.device/AHI_BestAudioIDA
  490.  
  491. NAME
  492.        AHI_BestAudioIDA -- calculate the best ModeID with given parameters
  493.        AHI_BestAudioID -- varargs stub for AHI_BestAudioIDA()
  494.  
  495.  
  496. SYNOPSIS
  497.        ID = AHI_BestAudioIDA( tags );
  498.        D0                     A1
  499.  
  500.        ULONG AHI_BestAudioIDA( struct TagItem * );
  501.  
  502.        ID = AHI_BestAudioID( tag1, ... );
  503.  
  504.        ULONG AHI_BestAudioID( Tag, ... );
  505.  
  506.  
  507. FUNCTION
  508.        Determines the best AudioID to fit the parameters set in the tag
  509.        list.
  510.  
  511.  
  512. INPUTS
  513.        tags - A pointer to a tag list. Only the tags present matter.
  514.  
  515.  
  516. TAGS
  517.        Many combinations are probably stupid to ask for, like not supporting
  518.        panning or recording.
  519.  
  520.        AHIDB_AudioID (ULONG) - The mode must use the same audio hardware
  521.            as this mode does.
  522.  
  523.        AHIDB_Volume (BOOL) - If TRUE: mode must support volume changes.
  524.            If FALSE: mode must not support volume changes.
  525.  
  526.        AHIDB_Stereo (BOOL) - If TRUE: mode must have stereo output.
  527.            If FALSE: mode must not have stereo output (=mono).
  528.  
  529.        AHIDB_Panning (BOOL) - If TRUE: mode must support volume panning.
  530.            If FALSE: mode must not support volume panning. 
  531.  
  532.        AHIDB_HiFi (BOOL) - If TRUE: mode must have HiFi output.
  533.            If FALSE: mode must not have HiFi output.
  534.  
  535.        AHIDB_PingPong (BOOL) - If TRUE: mode must support playing samples
  536.            backwards. If FALSE: mode must not support playing samples
  537.            backwards.
  538.  
  539.        AHIDB_Record (BOOL) - If TRUE: mode must support recording. If FALSE:
  540.            mode must not support recording.
  541.  
  542.        AHIDB_Realtime (BOOL) - If TRUE: mode must be realtime. If FALSE:
  543.            take a wild guess.
  544.  
  545.        AHIDB_FullDuplex (BOOL) - If TRUE: mode must be able to record and
  546.            play at the same time.
  547.  
  548.        AHIDB_Bits (UBYTE) - Mode must have greater or equal number of bits.
  549.  
  550.        AHIDB_MaxChannels (UWORD) - Mode must have greater or equal number
  551.            of channels.
  552.  
  553.        AHIDB_MinMixFreq (ULONG) - Lowest mixing frequency supported must be
  554.            less or equal.
  555.  
  556.        AHIDB_MaxMixFreq (ULONG) - Highest mixing frequency must be greater
  557.            or equal.
  558.  
  559.        AHIB_Dizzy (struct TagItem *) - This tag points to a second tag list.
  560.            After all other tags has been tested, the mode that matches these
  561.            tags best is returned, i.e. the one that has most of the features
  562.            you ask for, and least of the ones you don't want. Without this
  563.            second tag list, this function hardly does what its name
  564.            suggests. (V4)
  565.  
  566.  
  567. RESULT
  568.        ID - The best AudioID to use or AHI_INVALID_ID if none of the modes
  569.            in the audio database could meet the requirements.
  570.  
  571.  
  572. EXAMPLE
  573.  
  574.  
  575. NOTES
  576.  
  577.  
  578. BUGS
  579.        Due to a bug in the code that compared the boolean tag values in
  580.        version 4.158 and earlier, TRUE must be equal to 1. The bug is not
  581.        present in later revisions.
  582.  
  583.  
  584.  
  585. SEE ALSO
  586.       AHI_NextAudioID(), AHI_GetAudioAttrsA()
  587.  
  588.  
  589. ahi.device/AHI_ControlAudioA
  590.  
  591. NAME
  592.        AHI_ControlAudioA -- change audio attributes
  593.        AHI_ControlAudio -- varargs stub for AHI_ControlAudioA()
  594.  
  595.  
  596. SYNOPSIS
  597.        error = AHI_ControlAudioA( audioctrl, tags );
  598.        D0                         A2         A1
  599.  
  600.        ULONG AHI_ControlAudioA( struct AHIAudioCtrl *, struct TagItem * );
  601.  
  602.        error = AHI_ControlAudio( AudioCtrl, tag1, ...);
  603.  
  604.        ULONG AHI_ControlAudio( struct AHIAudioCtrl *, Tag, ... );
  605.  
  606.  
  607. FUNCTION
  608.        This function should be used to change attributes for a given
  609.        AHIAudioCtrl structure. It is also used to start and stop playback,
  610.        and to control special hardware found on some sound cards.
  611.  
  612.  
  613. INPUTS
  614.        audioctrl - A pointer to an AHIAudioCtrl structure.
  615.        tags - A pointer to a tag list.
  616.  
  617.  
  618. TAGS
  619.        AHIC_Play (BOOL) - Starts (TRUE) and stops (FALSE) playback and
  620.            PlayerFunc. NOTE: If the audio hardware cannot play at the same
  621.            time as recording samples, the recording will be stopped.
  622.  
  623.        AHIC_Record (BOOL) - Starts (TRUE) and stops (FALSE) sampling and
  624.            RecordFunc. NOTE: If the audio hardware cannot record at the same
  625.            time as playing samples, the playback will be stopped.
  626.  
  627.        AHIC_MonitorVolume (Fixed) - Sets the input monitor volume, i.e. how
  628.            much of the input signal is mixed with the output signal while
  629.            recording. Use AHI_GetAudioAttrsA() to find the available range.
  630.  
  631.        AHIC_MonitorVolume_Query (Fixed *) - Get the current input monitor
  632.            volume. ti_Data is a pointer to a Fixed variable, where the result
  633.            will be stored.
  634.  
  635.        AHIC_MixFreq_Query (ULONG *) - Get the current mixing frequency.
  636.            ti_Data is a pointer to an ULONG variable, where the result will
  637.            be stored.
  638.  
  639.        AHIC_InputGain (Fixed) - Set the input gain. Use AHI_GetAudioAttrsA()
  640.            to find the available range. (V2)
  641.  
  642.        AHIC_InputGain_Query (Fixed *) - Get current input gain. (V2)
  643.  
  644.        AHIC_OutputVolume (Fixed) - Set the output volume. Use
  645.            AHI_GetAudioAttrsA() to find the available range. (V2)
  646.  
  647.        AHIC_OutputVolume_Query (Fixed *) - Get current output volume. (V2)
  648.  
  649.        AHIC_Input (ULONG) - Select input source. See AHI_GetAudioAttrsA().
  650.            (V2)
  651.  
  652.        AHIC_Input_Query (ULONG *) - Get current input source. (V2)
  653.  
  654.        AHIC_Output (ULONG) - Select destination for output. See
  655.            AHI_GetAudioAttrsA(). (V2)
  656.  
  657.        AHIC_Output_Query (ULONG *) - Get destination for output. (V2)
  658.  
  659.        The following tags are also recognized by AHI_ControlAudioA(). See
  660.        AHI_AllocAudioA() for what they do. They may be used from interrupts.
  661.  
  662.        AHIA_SoundFunc (struct Hook *)
  663.        AHIA_PlayerFunc (struct Hook *)
  664.        AHIA_PlayerFreq (Fixed)
  665.        AHIA_RecordFunc (struct Hook *)
  666.        AHIA_UserData (APTR)
  667.  
  668.        Note that AHIA_PlayerFreq must never be outside the limits specified
  669.        with AHIA_MinPlayerFreq and AHIA_MaxPlayerFreq! Also note that the
  670.        timing feature is designed to be used for music. When you change the
  671.        frequency, be reasonable. Using 50 Hz one moment and 5 the other is
  672.        to ask for trouble.
  673.  
  674.  
  675. RESULT
  676.        An error code, defined in <devices/ahi.h>.
  677.  
  678.  
  679. EXAMPLE
  680.  
  681.  
  682. NOTES
  683.        The AHIC_Play and AHIC_Record tags *must not* be used from
  684.        interrupts.
  685.  
  686.  
  687. BUGS
  688.  
  689.  
  690. SEE ALSO
  691.        AHI_AllocAudioA(), AHI_GetAudioAttrsA(), <devices/ahi.h>
  692.  
  693.  
  694. ahi.device/AHI_FreeAudio
  695.  
  696. NAME
  697.        AHI_FreeAudio -- deallocates the audio hardware
  698.  
  699.  
  700. SYNOPSIS
  701.        AHI_FreeAudio( audioctrl );
  702.                       A2
  703.  
  704.        void AHI_FreeAudio( struct AHIAudioCtrl * );
  705.  
  706.  
  707. FUNCTION
  708.        Deallocates the AHIAudioCtrl structure and any other resources
  709.        allocated by AHI_AllocAudioA(). After this call it must not be used
  710.        by any other functions anymore. AHI_UnloadSound() is automatically
  711.        called for every sound.
  712.  
  713.  
  714. INPUTS
  715.        audioctrl - A pointer to an AHIAudioCtrl structure obtained from
  716.            AHI_AllocAudioA(). If NULL, this function does nothing.
  717.  
  718.  
  719. EXAMPLE
  720.  
  721.  
  722. NOTES
  723.  
  724.  
  725. BUGS
  726.  
  727.  
  728. SEE ALSO
  729.        AHI_AllocAudioA(), AHI_UnloadSound()
  730.  
  731.  
  732. ahi.device/AHI_FreeAudioRequest
  733.  
  734. NAME
  735.        AHI_FreeAudioRequest -- frees requester resources 
  736.  
  737.  
  738. SYNOPSIS
  739.        AHI_FreeAudioRequest( requester );
  740.                              A0
  741.  
  742.        void AHI_FreeAudioRequest( struct AHIAudioModeRequester * );
  743.  
  744.  
  745. FUNCTION
  746.        Frees any resources allocated by AHI_AllocAudioRequestA(). Once a
  747.        requester has been freed, it can no longer be used with other calls to
  748.        AHI_AudioRequestA().
  749.  
  750.  
  751. INPUTS
  752.        requester - Requester obtained from AHI_AllocAudioRequestA(), or NULL
  753.        in which case this function does nothing.
  754.  
  755.  
  756. RESULT
  757.  
  758.  
  759. EXAMPLE
  760.  
  761.  
  762. NOTES
  763.  
  764.  
  765. BUGS
  766.  
  767.  
  768. SEE ALSO
  769.       AHI_AllocAudioRequestA()
  770.  
  771.  
  772. ahi.device/AHI_GetAudioAttrsA
  773.  
  774. NAME
  775.        AHI_GetAudioAttrsA -- examine an audio mode via a tag list
  776.        AHI_GetAudioAttrs -- varargs stub for AHI_GetAudioAttrsA()
  777.  
  778.  
  779. SYNOPSIS
  780.        success = AHI_GetAudioAttrsA( ID, [audioctrl], tags );
  781.        D0                            D0  A2           A1
  782.  
  783.        BOOL AHI_GetAudioAttrsA( ULONG, struct AHIAudioCtrl *,
  784.                                 struct TagItem * );
  785.  
  786.        success = AHI_GetAudioAttrs( ID, [audioctrl], attr1, &result1, ...);
  787.  
  788.        BOOL AHI_GetAudioAttrs( ULONG, struct AHIAudioCtrl *, Tag, ... );
  789.  
  790.  
  791. FUNCTION
  792.        Retrieve information about an audio mode specified by ID or audioctrl
  793.        according to the tags in the tag list. For each entry in the tag
  794.        list, ti_Tag identifies the attribute, and ti_Data is mostly a
  795.        pointer to a LONG (4 bytes) variable where you wish the result to be
  796.        stored.
  797.  
  798.  
  799. INPUTS
  800.        ID - An audio mode identifier, AHI_DEFAULT_ID (V4) or AHI_INVALID_ID.
  801.        audioctrl - A pointer to an AHIAudioCtrl structure, only used if
  802.            ID equals AHI_INVALID_ID. Set to NULL if not used. If set to
  803.            NULL when used, this function returns immediately. Always set
  804.            ID to AHI_INVALID_ID and use audioctrl if you have allocated
  805.            a valid AHIAudioCtrl structure. Some of the tags return incorrect
  806.            values otherwise.
  807.        tags - A pointer to a tag list.
  808.  
  809.  
  810. TAGS
  811.        AHIDB_Volume (ULONG *) - TRUE if this mode supports volume changes.
  812.  
  813.        AHIDB_Stereo (ULONG *) - TRUE if output is in stereo. Unless
  814.            AHIDB_Panning (see below) is TRUE, all even channels are played
  815.            to the left and all odd to the right.
  816.  
  817.        AHIDB_Panning (ULONG *) - TRUE if this mode supports stereo panning.
  818.  
  819.        AHIDB_HiFi (ULONG *) - TRUE if no shortcuts, like pre-division, is
  820.            used by the mixing routines.
  821.  
  822.        AHIDB_PingPong (ULONG *) - TRUE if this mode can play samples backwards.
  823.  
  824.        AHIDB_Record (ULONG *) - TRUE if this mode can record samples.
  825.  
  826.        AHIDB_FullDuplex (ULONG *) - TRUE if this mode can record and play at
  827.            the same time.
  828.  
  829.        AHIDB_Realtime (ULONG *) - Modes which return TRUE for this fulfills
  830.            two criteria:
  831.            1) Calls to AHI_SetVol(), AHI_SetFreq() or AHI_SetSound() will be
  832.               performed within (about) 10 ms if called from a PlayFunc Hook.
  833.            2) The PlayFunc Hook will be called at the specified frequency.
  834.            If you don't use AHI's PlayFunc Hook, you must not use modes that
  835.            are not realtime. (Criterium 2 is not that obvious if you consider
  836.            a mode that renders the output to disk as a sample.)
  837.  
  838.        AHIDB_Bits (ULONG *) - The number of output bits (8, 12, 14, 16 etc).
  839.  
  840.        AHIDB_MaxChannels (ULONG *) - The maximum number of channels this mode
  841.            can handle.
  842.  
  843.        AHIDB_MinMixFreq (ULONG *) - The minimum mixing frequency supported.
  844.  
  845.        AHIDB_MaxMixFreq (ULONG *) - The maximum mixing frequency supported.
  846.  
  847.        AHIDB_Frequencies (ULONG *) - The number of different sample rates
  848.            available.
  849.  
  850.        AHIDB_FrequencyArg (ULONG) - Specifies which frequency
  851.            AHIDB_Frequency should return (see below). Range is 0 to
  852.            AHIDB_Frequencies-1 (including).
  853.            NOTE: ti_Data is NOT a pointer, but an ULONG.
  854.  
  855.        AHIDB_Frequency (ULONG *) - Return the frequency associated with the
  856.            index number specified with AHIDB_FrequencyArg (see above).
  857.  
  858.        AHIDB_IndexArg (ULONG) - AHIDB_Index will return the index which
  859.            gives the closest frequency to AHIDB_IndexArg
  860.            NOTE: ti_Data is NOT a pointer, but an ULONG.
  861.  
  862.        AHIDB_Index (ULONG *) - Return the index associated with the frequency
  863.            specified with AHIDB_IndexArg (see above).
  864.  
  865.        AHIDB_MaxPlaySamples (ULONG *) - Return the lowest number of sample
  866.            frames that must be present in memory when AHIST_DYNAMICSAMPLE
  867.            sounds are used. This number must then be scaled by Fs/Fm, where
  868.            Fs is the frequency of the sound and Fm is the mixing frequency.
  869.  
  870.        AHIDB_MaxRecordSamples (ULONG *) - Return the number of sample frames
  871.            you will receive each time the RecordFunc is called.
  872.  
  873.        AHIDB_BufferLen (ULONG) - Specifies how many characters will be
  874.            copied when requesting text attributes. Default is 0, which
  875.            means that AHIDB_Driver, AHIDB_Name, AHIDB_Author,
  876.            AHIDB_Copyright, AHIDB_Version and AHIDB_Annotation,
  877.            AHIDB_Input and AHIDB_Output will do nothing.
  878.  
  879.        AHIDB_Driver (STRPTR) - Name of driver (excluding path and
  880.            extension). 
  881.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  882.            will be stored. See AHIDB_BufferLen.
  883.  
  884.        AHIDB_Name (STRPTR) - Human readable name of this mode.
  885.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  886.            will be stored. See AHIDB_BufferLen.
  887.  
  888.        AHIDB_Author (STRPTR) - Name of driver author.
  889.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  890.            will be stored. See AHIDB_BufferLen.
  891.  
  892.        AHIDB_Copyright (STRPTR) - Driver copyright notice.
  893.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  894.            will be stored. See AHIDB_BufferLen
  895.  
  896.        AHIDB_Version (STRPTR) - Driver version string.
  897.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  898.            will be stored. See AHIDB_BufferLen.
  899.  
  900.        AHIDB_Annotation (STRPTR) - Annotation by driver author.
  901.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  902.            will be stored. See AHIDB_BufferLen.
  903.  
  904.        AHIDB_MinMonitorVolume (Fixed *)
  905.        AHIDB_MaxMonitorVolume (Fixed *) - Lower/upper limit for input
  906.            monitor volume, see AHI_ControlAudioA(). If both are 0.0,
  907.            the sound hardware does not have an input monitor feature.
  908.            If both are same, but not 0.0, the hardware always sends the
  909.            recorded sound to the outputs (at the given volume). (V2)
  910.  
  911.        AHIDB_MinInputGain (Fixed *)
  912.        AHIDB_MaxInputGain (Fixed *) - Lower/upper limit for input gain,
  913.            see AHI_ControlAudioA(). If both are same, there is no input
  914.            gain hardware. (V2)
  915.  
  916.        AHIDB_MinOutputVolume (Fixed *)
  917.        AHIDB_MaxOutputVolume (Fixed *) - Lower/upper limit for output
  918.            volume, see AHI_ControlAudioA(). If both are same, the sound
  919.            card does not have volume control. (V2)
  920.  
  921.        AHIDB_Inputs (ULONG *) - The number of inputs the sound card has.
  922.            (V2)
  923.  
  924.        AHIDB_InputArg (ULONG) - Specifies what AHIDB_Input should return
  925.            (see below). Range is 0 to AHIDB_Inputs-1 (including).
  926.            NOTE: ti_Data is NOT a pointer, but an ULONG. (V2)
  927.  
  928.        AHIDB_Input (STRPTR) - Gives a human readable string describing the
  929.            input associated with the index specified with AHIDB_InputArg
  930.            (see above). See AHI_ControlAudioA() for how to select one.
  931.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  932.            will be stored. See AHIDB_BufferLen. (V2)
  933.  
  934.        AHIDB_Outputs (ULONG *) - The number of outputs the sound card
  935.            has. (V2)
  936.  
  937.        AHIDB_OutputArg (ULONG) - Specifies what AHIDB_Output should return
  938.            (see below). Range is 0 to AHIDB_Outputs-1 (including)
  939.            NOTE: ti_Data is NOT a pointer, but an ULONG. (V2)
  940.  
  941.        AHIDB_Output (STRPTR) - Gives a human readable string describing the
  942.            output associated with the index specified with AHIDB_OutputArg
  943.            (see above). See AHI_ControlAudioA() for how to select one.
  944.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  945.            will be stored. See AHIDB_BufferLen. (V2)
  946.  
  947.        AHIDB_AudioID (ULONG *) - The ID for this mode. (V4)
  948.  
  949.        If the requested information cannot be found, the variable will be not
  950.        be touched.
  951.  
  952.  
  953. RESULT
  954.        TRUE if everything went well.
  955.  
  956.  
  957. EXAMPLE
  958.  
  959.  
  960. NOTES
  961.  
  962.  
  963. BUGS
  964.        In versions earlier than 3, the tags that filled a string buffer would
  965.        not NULL-terminate the string on buffer overflows.
  966.  
  967.  
  968. SEE ALSO
  969.       AHI_NextAudioID(), AHI_BestAudioIDA()
  970.  
  971.  
  972. ahi.device/AHI_LoadSound
  973.  
  974. NAME
  975.        AHI_LoadSound -- prepare a sound for playback
  976.  
  977.  
  978. SYNOPSIS
  979.        error = AHI_LoadSound( sound, type, info, audioctrl );
  980.        D0                     D0:16  D1    A0    A2
  981.  
  982.        ULONG AHI_LoadSound( UWORD, ULONG, APTR, struct AHIAudioCtrl * );
  983.  
  984.  
  985. FUNCTION
  986.        Defines an ID number for the sound and prepares it for playback.
  987.  
  988.  
  989. INPUTS
  990.        sound - The numeric ID to be used as a reference to this sound.
  991.            The ID is a number greater or equal to 0 and less than what you
  992.            specified with AHIA_Sounds when you called AHI_AllocAudioA().
  993.        type - The type of the sound. Currently four types are supported:
  994.            AHIST_SAMPLE - array of 8 or 16 bit samples. Note that the
  995.                portion of memory where the sample is stored must NOT be
  996.                altered until AHI_UnloadSound() has been called! This is
  997.                because some audio drivers may wish to upload the samples
  998.                to local RAM. It is OK to read, though.
  999.  
  1000.            AHIST_DYNAMICSAMPLE - array of 8 or 16 bit samples, which can be
  1001.                updated dynamically. Typically used to play data that is
  1002.                loaded from disk or calculated realtime.
  1003.                Avoid using this sound type as much as possible; it will
  1004.                use much more CPU power than AHIST_SAMPLE on a DMA/DSP
  1005.                sound card.
  1006.  
  1007.            AHIST_INPUT - The input from your sampler (not fully functional
  1008.                yet).
  1009.  
  1010.        info - Depends on type:
  1011.            AHIST_SAMPLE - A pointer to a struct AHISampleInfo, filled with:
  1012.                ahisi_Type - Format of samples (four formats are supported).
  1013.                    AHIST_M8S: Mono, 8 bit signed (BYTEs).
  1014.                    AHIST_S8S: Stereo, 8 bit signed (2×BYTEs) (V4). 
  1015.                    AHIST_M16S: Mono, 16 bit signed (WORDs).
  1016.                    AHIST_S16S: Stereo, 16 bit signed (2×WORDs) (V4).
  1017.                ahisi_Address - Address to the sample array.
  1018.                ahisi_Length - The size of the array, in samples.
  1019.                Don't even think of setting ahisi_Address to 0 and
  1020.                ahisi_Length to 0xffffffff as you can do with
  1021.                AHIST_DYNAMICSAMPLE! Very few DMA/DSP cards have 4 GB onboard
  1022.                RAM...
  1023.  
  1024.            AHIST_DYNAMICSAMPLE A pointer to a struct AHISampleInfo, filled
  1025.                as described above (AHIST_SAMPLE).
  1026.                If ahisi_Address is 0 and ahisi_Length is 0xffffffff
  1027.                AHI_SetSound() can take the real address of an 8 bit sample
  1028.                to be played as offset argument. Unfortunately, this does not
  1029.                work for 16 bit samples.
  1030.  
  1031.            AHIST_INPUT - Always set info to NULL.
  1032.                Note that AHI_SetFreq() may only be called with AHI_MIXFREQ
  1033.                for this sample type.
  1034.  
  1035.        audioctrl - A pointer to an AHIAudioCtrl structure.
  1036.  
  1037.  
  1038. RESULT
  1039.        An error code, defined in <devices/ahi.h>.
  1040.  
  1041.  
  1042. EXAMPLE
  1043.  
  1044.  
  1045. NOTES
  1046.        There is no need to place a sample array in Chip memory, but it
  1047.        MUST NOT be swapped out! Allocate your sample memory with the
  1048.        MEMF_PUBLIC flag set. 
  1049.  
  1050.  
  1051. BUGS
  1052.        AHIST_INPUT does not fully work yet.
  1053.  
  1054.  
  1055. SEE ALSO
  1056.        AHI_UnloadSound(), AHI_SetEffect(), AHI_SetFreq(), AHI_SetSound(),
  1057.        AHI_SetVol(), <devices/ahi.h>
  1058.  
  1059.  
  1060. ahi.device/AHI_NextAudioID
  1061.  
  1062. NAME
  1063.        AHI_NextAudioID -- iterate current audio mode identifiers
  1064.  
  1065.  
  1066. SYNOPSIS
  1067.        next_ID = AHI_NextAudioID( last_ID );
  1068.        D0                         D0
  1069.  
  1070.        ULONG AHI_NextAudioID( ULONG );
  1071.  
  1072.  
  1073. FUNCTION
  1074.        This function is used to iterate through all current AudioIDs in
  1075.        the audio database.
  1076.  
  1077.  
  1078. INPUTS
  1079.        last_ID - previous AudioID or AHI_INVALID_ID if beginning iteration.
  1080.  
  1081.  
  1082. RESULT
  1083.        next_ID - subsequent AudioID or AHI_INVALID_ID if no more IDs.
  1084.  
  1085.  
  1086. EXAMPLE
  1087.  
  1088.  
  1089. NOTES
  1090.  
  1091.  
  1092. BUGS
  1093.  
  1094.  
  1095. SEE ALSO
  1096.       AHI_GetAudioAttrsA(), AHI_BestAudioIDA()
  1097.  
  1098.  
  1099. ahi.device/AHI_PlayA
  1100.  
  1101. NAME
  1102.        AHI_PlayA -- Start multiple sounds in one call (V4)
  1103.        AHI_Play -- varargs stub for AHI_PlayA()
  1104.  
  1105.  
  1106. SYNOPSIS
  1107.        AHI_PlayA( audioctrl, tags );
  1108.                   A2         A1
  1109.  
  1110.        void AHI_PlayA( struct AHIAudioCtrl *, struct TagItem * );
  1111.  
  1112.        AHI_Play( AudioCtrl, tag1, ...);
  1113.  
  1114.        void AHI_Play( struct AHIAudioCtrl *, Tag, ... );
  1115.  
  1116.  
  1117. FUNCTION
  1118.        This function performs the same actions as multiple calls to
  1119.        AHI_SetFreq(), AHI_SetSound() and AHI_SetVol(). The advantages
  1120.        of using only one call is that simple loops can be set without
  1121.        using a SoundFunc (see AHI_AllocAudioA(), tag AHIA_SoundFunc) and
  1122.        that sounds on different channels can be synchronized even when the
  1123.        sounds are not started from a PlayerFunc (see AHI_AllocAudioA(), tag
  1124.        AHIA_PlayerFunc). The disadvantage is that this call has more
  1125.        overhead than AHI_SetFreq(), AHI_SetSound() and AHI_SetVol(). It is
  1126.        therefore recommended that you only use this call if you are not
  1127.        calling from a SoundFunc or PlayerFunc.
  1128.  
  1129.        The supplied tag list works like a 'program'. This means that
  1130.        the order of tags matter.
  1131.  
  1132.  
  1133. INPUTS
  1134.        audioctrl - A pointer to an AHIAudioCtrl structure.
  1135.        tags - A pointer to a tag list.
  1136.  
  1137.  
  1138. TAGS
  1139.        AHIP_BeginChannel (UWORD) - Before you start setting attributes
  1140.            for a sound to play, you have to use this tag to chose a
  1141.            channel to operate on. If AHIP_BeginChannel is omitted, the
  1142.            result is undefined.
  1143.  
  1144.        AHIP_EndChannel (ULONG) - Signals the end of attributes for
  1145.            the current channel. If AHIP_EndChannel is omitted, the result
  1146.            is undefined. ti_Data MUST BE NULL!
  1147.  
  1148.        AHIP_Freq (ULONG) - The playback frequency in Hertz or AHI_MIXFREQ.
  1149.  
  1150.        AHIP_Vol (Fixed) - The desired volume. If omitted, but AHIP_Pan is
  1151.            present, AHIP_Vol defaults to 0.
  1152.  
  1153.        AHIP_Pan (sposition) - The desired panning. If omitted, but AHIP_Vol
  1154.            is present, AHIP_Pan defaults to 0 (extreme left).
  1155.  
  1156.        AHIP_Sound (UWORD) - Sound to be played, or AHI_NOSOUND.
  1157.  
  1158.        AHIP_Offset (ULONG) - Specifies an offset (in samples) into the
  1159.            sound. If this tag is present, AHIP_Length MUST be present too!
  1160.  
  1161.        AHIP_Length (LONG) - Specifies how many samples that should be
  1162.            player.
  1163.  
  1164.        AHIP_LoopFreq (ULONG)
  1165.        AHIP_LoopVol (Fixed)
  1166.        AHIP_LoopPan (sposition)
  1167.        AHIP_LoopSound (UWORD)
  1168.        AHIP_LoopOffset (ULONG)
  1169.        AHIP_LoopLength (LONG) - These tags can be used to set simple loop
  1170.           attributes. They default to their sisters. These tags must be
  1171.           after the other tags.
  1172.  
  1173.  
  1174. RESULT
  1175.  
  1176.  
  1177. EXAMPLE
  1178.  
  1179.  
  1180. NOTES
  1181.  
  1182.  
  1183. BUGS
  1184.  
  1185.  
  1186. SEE ALSO
  1187.        AHI_SetFreq(), AHI_SetSound(), AHI_SetVol()
  1188.  
  1189.  
  1190. ahi.device/AHI_SampleFrameSize
  1191.  
  1192. NAME
  1193.        AHI_SampleFrameSize -- get the size of a sample frame (V4)
  1194.  
  1195.  
  1196. SYNOPSIS
  1197.        size = AHI_SampleFrameSize( sampletype );
  1198.        D0                          D0
  1199.  
  1200.        ULONG AHI_SampleFrameSize( ULONG );
  1201.  
  1202.  
  1203. FUNCTION
  1204.        Returns the size in bytes of a sample frame for a given sample type.
  1205.  
  1206.  
  1207. INPUTS
  1208.        sampletype - The sample type to examine. See <devices/ahi.h> for
  1209.            possible types.
  1210.  
  1211.  
  1212. RESULT
  1213.  
  1214.  
  1215. EXAMPLE
  1216.  
  1217.  
  1218. NOTES
  1219.  
  1220.  
  1221. BUGS
  1222.  
  1223.  
  1224. SEE ALSO
  1225.       <devices/ahi.h>
  1226.  
  1227.  
  1228. ahi.device/AHI_SetEffect
  1229.  
  1230. NAME
  1231.        AHI_SetEffect -- set effect
  1232.  
  1233.  
  1234. SYNOPSIS
  1235.        error = AHI_SetEffect( effect, audioctrl );
  1236.        d0                     A0      A2
  1237.  
  1238.        ULONG AHI_SetEffect( APTR, struct AHIAudioCtrl * );
  1239.  
  1240.  
  1241. FUNCTION
  1242.        Selects an effect to be used, described by a structure.
  1243.  
  1244.  
  1245. INPUTS
  1246.        effect - A pointer to an effect data structure, as defined in
  1247.            <devices/ahi.h>. The following effects are defined:
  1248.            AHIET_MASTERVOLUME - Changes the volume for all channels. Can
  1249.                also be used to boost volume over 100%.
  1250.            AHIET_OUTPUTBUFFER - Gives READ-ONLY access to the mixed output.
  1251.                Can be used to show nice scopes and VU-meters.
  1252.            AHIET_DSPMASK - Select which channels will be affected by the
  1253.                DSP effects. (V4)
  1254.            AHIET_DSPECHO - A DSP effects that adds (cross-)echo and delay.
  1255.                (V4)
  1256.            AHIET_CHANNELINFO - Get info about all channels. (V4)
  1257.        audioctrl - A pointer to an AHIAudioCtrl structure.
  1258.  
  1259.  
  1260. EFFECTS
  1261.        AHIET_MASTERVOLUME - Effect is a struct AHIEffMasterVolume, with
  1262.            ahiemv_Volume set to the desired volume. The range is 0 to
  1263.            (channels/hardware channel). Assume you have 4 channels in
  1264.            mono mode. The range is then 0.0 to 4.0. The range is the same
  1265.            if the mode is stereo with panning. However, assume you have 4
  1266.            channels with a stereo mode *without* panning. Then you have two
  1267.            channels to the left and two to the right => range is 0.0 - 2.0.
  1268.            Setting the volume outside the range will give an unpredictable
  1269.            result!
  1270.  
  1271.        AHIET_OUTPUTBUFFER - Effect is a struct AHIEffOutputBuffer, with
  1272.            ahieob_Func pointing to a hook that will be called with the
  1273.            following parameters:
  1274.                A0 - (struct Hook *)
  1275.                A2 - (struct AHIAudioCtrl *)
  1276.                A1 - (struct AHIEffOutputBuffer *)
  1277.            The information you are looking for then is in ahieob_Type,
  1278.            ahieob_Buffer and ahieob_Length. Always check ahieob_Type!
  1279.            ahieob_Length is neither in bytes nor samples, but sample frames.
  1280.  
  1281.        AHIET_DSPMASK - Effect is a struct AHIEffDSPMask, where ahiedm_Mask
  1282.            is an array with ahiedm_Channels elements. Each UBYTE in the
  1283.            array can either make the channel 'wet' (affected by the DSP
  1284.            effects), by using the AHIEDM_WET constant or 'dry' (not
  1285.            affected by the DSP effects) by using the AHIEDM_DRY constant.
  1286.            The default is all channels wet. If ahiedm_Channels does not
  1287.            equal the current number of channels allocated, the result of
  1288.            this call is undefined (crash warning!). (V4)
  1289.  
  1290.        AHIET_DSPECHO - Effect is a struct AHIEffDSPEcho.
  1291.            ahiede_Delay is the delay in samples (and thus depends on the
  1292.            mixing rate).
  1293.  
  1294.            ahiede_Feedback is a Fixed value between 0 and 1.0, and defines
  1295.            how much of the delayed signal should be feed back to the delay
  1296.            stage. Setting this to 0 gives a delay effect, otherwise echo.
  1297.  
  1298.            ahiede_Mix tells how much of the delayed signal should be mixed
  1299.            with the normal signal. Setting this to 0 disables delay/echo,
  1300.            and setting it to 1.0 outputs only the delay/echo signal.
  1301.  
  1302.            ahiede_Cross only has effect of the current playback mode is
  1303.            stereo. It tells how the delayed signal should be panned to
  1304.            the other channel. 0 means no cross echo, 1.0 means full
  1305.            cross echo.
  1306.  
  1307.            If the user has enabled "Fast Echo", AHI may take several short-
  1308.            cuts to increase the performance. This could include rounding the
  1309.            parameters to a power of two, or even to the extremes. 
  1310.  
  1311.            If you set ahiede_Mix to 0x10000 and ahiede_Cross to 0x0, much
  1312.            faster mixing routines will be used, and "Fast Echo" will improve
  1313.            that even more.
  1314.  
  1315.            Otherwise, even with "Fast Echo" turned on, this effect will 
  1316.            probably suck some major CPU cycles on most sound hardware. (V4)
  1317.  
  1318.        AHIET_CHANNELINFO - Effect is a struct AHIEffChannelInfo, where
  1319.            ahieci_Func is pointing to a hook that will be called with the
  1320.            following parameters:
  1321.                A0 - (struct Hook *)
  1322.                A2 - (struct AHIAudioCtrl *)
  1323.                A1 - (struct AHIEffChannelInfo *)
  1324.            ahieci_Channels must equal the current number of channels used.
  1325.            ahieci_Offset is an array of ULONGs, which will be filled by
  1326.            AHI before the hook is called (the offset is specified in sample
  1327.            frames). The array must have at least ahieci_Channels elements.
  1328.  
  1329.            This "effect" can be used to find out how far each channel has
  1330.            played. You must probably keep track of the other parameters
  1331.            yourself (like which sound is playing, it's volume, balance and
  1332.            frequency etc) in order have meaningful usage of the information.
  1333.            (V4)
  1334.  
  1335.  
  1336.        NOTE! To turn off an effect, call again with ahie_Effect OR:ed
  1337.        with AHIET_CANCEL. For example, it is NOT correct to disable
  1338.        the AHIET_MASTERVOLUME effect by setting ahiemv_Volume to 1.0!
  1339.  
  1340.        It is important that you always turn off effects before you
  1341.        deallocate the audio hardware. Otherwise memory may be lost.
  1342.        It is safe to turn off an effect that has never been turned on
  1343.        in the first place.
  1344.  
  1345.        Never count on that an effect will be available. For example,
  1346.        AHIET_OUTPUTBUFFER is impossible to implement with some sound
  1347.        cards.
  1348.  
  1349.  
  1350. RESULT
  1351.        An error code, defined in <devices/ahi.h>.
  1352.  
  1353.  
  1354. EXAMPLE
  1355.  
  1356.  
  1357. NOTES
  1358.        Unlike the other functions whose names begin with "AHI_Set", this
  1359.        function may NOT be called from an interrupt (or AHI Hook).
  1360.  
  1361.        Previous to V4, this call always returned AHIE_OK.
  1362.  
  1363.  
  1364. BUGS
  1365.        The idea of updating the source structure instead of allocating
  1366.        a new one that is passed the hook it pretty flawed. The reason is
  1367.        that AHI_SetEffect() originally could be called from interrupts,
  1368.        and memory allocation is not allowed from within interrupts.
  1369.  
  1370.  
  1371. SEE ALSO
  1372.        AHI_SetFreq(), AHI_SetSound(), AHI_SetVol(), AHI_LoadSound(),
  1373.        <devices/ahi.h>
  1374.  
  1375.  
  1376. ahi.device/AHI_SetFreq
  1377.  
  1378. NAME
  1379.        AHI_SetFreq -- set frequency for a channel
  1380.  
  1381.  
  1382. SYNOPSIS
  1383.        AHI_SetFreq( channel, freq, audioctrl, flags );
  1384.                     D0:16    D1    A2         D2
  1385.  
  1386.        void AHI_SetFreq( UWORD, ULONG, struct AHIAudioCtrl *, ULONG );
  1387.  
  1388.  
  1389. FUNCTION
  1390.        Sets the playback frequency for a channel.
  1391.  
  1392.  
  1393. INPUTS
  1394.        channel - The channel to set playback frequency for.
  1395.        freq - The playback frequency in Hertz. Can also be AHI_MIXFREQ,
  1396.            is the current mixing frequency (only usable with AHIST_INPUT
  1397.            sounds), or 0 to temporary stop the sound (it will restart at
  1398.            the same point when its frequency changed). Setting the frequency
  1399.            of an AHIST_INPUT sound is not supported, and the result is
  1400.            undefined.
  1401.        audioctrl - A pointer to an AHIAudioCtrl structure.
  1402.        flags - Only one flag is defined
  1403.            AHISF_IMM - Set this flag if this command should take effect
  1404.                immediately. If this bit is not set, the command will not
  1405.                take effect until the current sound is finished. MUST NOT
  1406.                be set if called from a SoundFunc. See the programming
  1407.                guidelines for more information about this flag.
  1408.  
  1409.  
  1410. RESULT
  1411.  
  1412.  
  1413. EXAMPLE
  1414.  
  1415.  
  1416. NOTES
  1417.        It is safe to call this function from an interrupt.
  1418.  
  1419.  
  1420. BUGS
  1421.  
  1422.  
  1423. SEE ALSO
  1424.        AHI_SetEffect(),  AHI_SetSound(), AHI_SetVol(), AHI_LoadSound()
  1425.  
  1426.  
  1427. ahi.device/AHI_SetSound
  1428.  
  1429. NAME
  1430.        AHI_SetSound -- set what sound to play for a channel
  1431.  
  1432.  
  1433. SYNOPSIS
  1434.        AHI_SetSound( channel, sound, offset, length, audioctrl, flags );
  1435.                       D0:16   D1:16   D2      D3      A2         D4
  1436.  
  1437.        void AHI_SetSound( UWORD, UWORD, ULONG, LONG,
  1438.                           struct AHIAudioCtrl *, ULONG );
  1439.  
  1440.  
  1441. FUNCTION
  1442.        Sets a sound to be played on a channel.
  1443.  
  1444.  
  1445. INPUTS
  1446.        channel - The channel to set sound for.
  1447.        sound - Sound to be played, or AHI_NOSOUND to turn the channel off.
  1448.        offset - Only available if the sound type is AHIST_SAMPLE or
  1449.            AHIST_DYNAMICSAMPLE. Must be 0 otherwise.
  1450.            Specifies an offset (in samples) where the playback will begin.
  1451.            If you wish to play the whole sound, set offset to 0.
  1452.        length - Only available if the sound type is AHIST_SAMPLE or
  1453.            AHIST_DYNAMICSAMPLE. Must be 0 otherwise.
  1454.            Specifies how many samples that should be played. If you
  1455.            wish to play the whole sound forwards, set offset to 0 and length
  1456.            to either 0 or the length of the sample array. You may not set
  1457.            length to 0 if offset is not 0! To play a sound backwards, just
  1458.            set length to a negative number.
  1459.        audioctrl - A pointer to an AHIAudioCtrl structure.
  1460.        flags - Only one flag is defined
  1461.            AHISF_IMM - Set this flag if this command should take effect
  1462.                immediately. If this bit is not set, the command will not
  1463.                take effect until the current sound is finished. MUST NOT
  1464.                be set if called from a SoundFunc. See the programming
  1465.                guidelines for more information about this flag.
  1466.  
  1467.  
  1468. RESULT
  1469.  
  1470.  
  1471. EXAMPLE
  1472.  
  1473.  
  1474. NOTES
  1475.        It is safe to call this function from an interrupt.
  1476.  
  1477.        If offset or length is not zero, make sure you do not exceed the
  1478.        sample limits.
  1479.  
  1480.  
  1481. BUGS
  1482.  
  1483.  
  1484. SEE ALSO
  1485.        AHI_SetEffect(),  AHI_SetFreq(), AHI_SetVol(), AHI_LoadSound()
  1486.  
  1487.  
  1488. ahi.device/AHI_SetVol
  1489.  
  1490. NAME
  1491.        AHI_SetVol -- set volume and stereo panning for a channel
  1492.  
  1493.  
  1494. SYNOPSIS
  1495.        AHI_SetVol( channel, volume, pan, audioctrl, flags );
  1496.                    D0:16    D1      D2   A2         D3
  1497.  
  1498.        void AHI_SetVol( UWORD, Fixed, sposition, struct AHIAudioCtrl *,
  1499.                         ULONG );
  1500.  
  1501.  
  1502. FUNCTION
  1503.        Changes the volume and stereo panning for a channel.
  1504.  
  1505.  
  1506. INPUTS
  1507.        channel - The channel to set volume for.
  1508.        volume - The desired volume. Fixed is a LONG fixed-point value with
  1509.            16 bits to the left of the point and 16 to the right
  1510.            (typedef LONG Fixed; from IFF-8SVX docs).
  1511.            Maximum volume is 1.0 (0x10000L) and 0.0 (0x0L) will turn off
  1512.            this channel. Note: The sound will continue to play, but you
  1513.            wont hear it. To stop a sound completely, use AHI_SetSound().
  1514.            Starting with V4 volume can also be negative, which tells AHI
  1515.            to invert the samples before playing. Note that all drivers
  1516.            may not be able to handle negative volume. In that case the
  1517.            absolute volume will be used.
  1518.        pan - The desired panning. sposition is the same as Fixed
  1519.            (typedef Fixed sposition; from IFF-8SVX.PAN docs).
  1520.            1.0 (0x10000L) means that the sound is panned all the way to
  1521.            the right, 0.5 (0x8000L) means the sound is centered and 0.0
  1522.            (0x0L) means that the sound is panned all the way to the left.
  1523.            Try to set Pan to the 'correct' value even if you know it has no
  1524.            effect. For example, if you know you use a mono mode, set pan to
  1525.            0.5 even if it does not matter.
  1526.            Starting with V4 pan can also be negative, which tells AHI to
  1527.            use the surround speaker for this channel. Note that all drivers
  1528.            may not be able to handle negative pan. In that case the absolute
  1529.            pan will be used.
  1530.        audioctrl - A pointer to an AHIAudioCtrl structure.
  1531.        flags - Only one flag is defined
  1532.            AHISF_IMM - Set this flag if this command should take effect
  1533.                immediately. If this bit is not set, the command will not
  1534.                take effect until the current sound is finished. MUST NOT
  1535.                be set if called from a SoundFunc. See the programming
  1536.                guidelines for more information about this flag.
  1537.  
  1538.  
  1539. RESULT
  1540.  
  1541.  
  1542. EXAMPLE
  1543.  
  1544.  
  1545. NOTES
  1546.        It is safe to call this function from an interrupt.
  1547.  
  1548.        Negative volume or negative pan may use more CPU time than positive.
  1549.  
  1550.        Using both negative volume and negative pan will play the inverted
  1551.        sound on the surround speaker.
  1552.  
  1553.  
  1554. BUGS
  1555.  
  1556.  
  1557. SEE ALSO
  1558.        AHI_SetEffect(), AHI_SetFreq(), AHI_SetSound(), AHI_LoadSound()
  1559.        
  1560.  
  1561.  
  1562. ahi.device/AHI_UnloadSound
  1563.  
  1564. NAME
  1565.        AHI_UnloadSound -- discard a sound
  1566.  
  1567.  
  1568. SYNOPSIS
  1569.        AHI_UnloadSound( sound, audioctrl );
  1570.                         D0:16  A2
  1571.  
  1572.        void AHI_UnloadSound( UWORD, struct AHIAudioCtrl * );
  1573.  
  1574.  
  1575. FUNCTION
  1576.        Tells 'ahi.device' that this sound will not be used anymore.
  1577.  
  1578.  
  1579. INPUTS
  1580.        sound - The ID of the sound to unload.
  1581.        audioctrl - A pointer to an AHIAudioCtrl structure.
  1582.  
  1583.  
  1584. RESULT
  1585.  
  1586.  
  1587. EXAMPLE
  1588.  
  1589.  
  1590. NOTES
  1591.        This call will not break a Forbid() state.
  1592.  
  1593.  
  1594. BUGS
  1595.  
  1596.  
  1597. SEE ALSO
  1598.        AHI_LoadSound()
  1599.  
  1600.  
  1601. ahi.device/CMD_FLUSH
  1602.  
  1603. NAME
  1604.        CMD_FLUSH -- Cancel all I/O requests (V4)
  1605.  
  1606.  
  1607. FUNCTION
  1608.        Aborts ALL current requests, both active and waiting, even
  1609.        other programs requests!
  1610.  
  1611.  
  1612. IO REQUEST INPUT
  1613.        io_Device       Preset by the call to OpenDevice().
  1614.        io_Unit         Preset by the call to OpenDevice().
  1615.        io_Command      CMD_FLUSH
  1616.  
  1617.  
  1618. IO REQUEST RESULT
  1619.        io_Error        0 for success, or an error code as defined in
  1620.                        <ahi/devices.h> and <exec/errors.h>.
  1621.        io_Actual       If io_Error is 0, number of requests actually
  1622.                        flushed.
  1623.  
  1624.        The other fields, except io_Device, io_Unit and io_Command, are
  1625.        trashed.
  1626.  
  1627.  
  1628. EXAMPLE
  1629.  
  1630.  
  1631. NOTES
  1632.        This command should only be used in very rare cases, like AHI
  1633.        system utilities. Never use this command in an application.
  1634.  
  1635.  
  1636. BUGS
  1637.  
  1638.  
  1639. SEE ALSO
  1640.        CMD_RESET, <ahi/devices.h>, <exec/errors.h>
  1641.  
  1642.  
  1643. ahi.device/CMD_READ
  1644.  
  1645. NAME
  1646.        CMD_READ -- Read raw samples from audio input (V4)
  1647.  
  1648.  
  1649. FUNCTION
  1650.        Reads samples from the users prefered input to memory. The sample
  1651.        format and frequency will be converted on the fly. 
  1652.  
  1653.  
  1654. IO REQUEST INPUT
  1655.        io_Device       Preset by the call to OpenDevice().
  1656.        io_Unit         Preset by the call to OpenDevice().
  1657.        io_Command      CMD_READ
  1658.        io_Data         Pointer to the buffer where the data should be put.
  1659.        io_Length       Number of bytes to read, must be a multiple of the
  1660.                        sample frame size (see ahir_Type).
  1661.        io_Offset       Set to 0 when you use for the first time or after
  1662.                        a delay.
  1663.        ahir_Type       The desired sample format, see <ahi/devices.h>.
  1664.        ahir_Frequency  The desired sample frequency in Hertz.
  1665.  
  1666.  
  1667. IO REQUEST RESULT
  1668.        io_Error        0 for success, or an error code as defined in
  1669.                        <ahi/devices.h> and <exec/errors.h>.
  1670.        io_Actual       If io_Error is 0, number of bytes actually
  1671.                        transferred.
  1672.        io_Offset       Updated to be used as input next time.
  1673.  
  1674.        The other fields, except io_Device, io_Unit and io_Command, are
  1675.        trashed.
  1676.  
  1677.  
  1678. EXAMPLE
  1679.  
  1680.  
  1681. NOTES
  1682.  
  1683.  
  1684. BUGS
  1685.  
  1686.  
  1687. SEE ALSO
  1688.        <ahi/devices.h>, <exec/errors.h>
  1689.  
  1690.  
  1691. ahi.device/CMD_RESET
  1692.  
  1693. NAME
  1694.        CMD_RESET -- Restore device to a known state (V4)
  1695.  
  1696.  
  1697. FUNCTION
  1698.        Aborts all current requests, even other programs requests
  1699.        (CMD_FLUSH), rereads the configuration file and resets the hardware
  1700.        to its initial state
  1701.        
  1702.  
  1703.  
  1704. IO REQUEST INPUT
  1705.        io_Device       Preset by the call to OpenDevice().
  1706.        io_Unit         Preset by the call to OpenDevice().
  1707.        io_Command      CMD_RESET
  1708.  
  1709.  
  1710. IO REQUEST RESULT
  1711.        io_Error        0 for success, or an error code as defined in
  1712.                        <ahi/devices.h> and <exec/errors.h>.
  1713.  
  1714.        The other fields, except io_Device, io_Unit and io_Command, are
  1715.        trashed.
  1716.  
  1717.  
  1718. EXAMPLE
  1719.  
  1720.  
  1721. NOTES
  1722.        This command should only be used in very rare cases, like AHI
  1723.        system utilities. Never use this command in an application.
  1724.  
  1725.  
  1726. BUGS
  1727.  
  1728.  
  1729. SEE ALSO
  1730.        CMD_FLUSH, <ahi/devices.h>, <exec/errors.h>
  1731.  
  1732.  
  1733. ahi.device/CMD_START
  1734.  
  1735. NAME
  1736.        CMD_START -- start device processing (like ^Q) (V4)
  1737.  
  1738.  
  1739. FUNCTION
  1740.        All CMD_WRITE's that has been sent to the device since CMD_STOP
  1741.        will be started at once, synchronized.
  1742.  
  1743.  
  1744. IO REQUEST INPUT
  1745.        io_Device       Preset by the call to OpenDevice().
  1746.        io_Unit         Preset by the call to OpenDevice().
  1747.        io_Command      CMD_START
  1748.  
  1749.  
  1750. IO REQUEST RESULT
  1751.        io_Error        0 for success, or an error code as defined in
  1752.                        <ahi/devices.h> and <exec/errors.h>.
  1753.        io_Actual       If io_Error is 0, number of requests actually
  1754.                        flushed.
  1755.  
  1756.        The other fields, except io_Device, io_Unit and io_Command, are
  1757.        trashed.
  1758.  
  1759.  
  1760. EXAMPLE
  1761.  
  1762.  
  1763. NOTES
  1764.        Unlike most (all?) other devices, CMD_STOP and CMD_START do nest in
  1765.        ahi.device.
  1766.  
  1767.  
  1768. BUGS
  1769.  
  1770.  
  1771. SEE ALSO
  1772.        CMD_STOP, <ahi/devices.h>, <exec/errors.h>
  1773.  
  1774.  
  1775. ahi.device/CMD_STOP
  1776.  
  1777. NAME
  1778.        CMD_STOP -- stop device processing (like ^S) (V4)
  1779.  
  1780.  
  1781. FUNCTION
  1782.        Stops all CMD_WRITE processing. All writes will be queued, and
  1783.        are not processed until CMD_START. This is useful for synchronizing
  1784.        two or more CMD_WRITE's.
  1785.  
  1786.  
  1787. IO REQUEST INPUT
  1788.        io_Device       Preset by the call to OpenDevice().
  1789.        io_Unit         Preset by the call to OpenDevice().
  1790.        io_Command      CMD_STOP
  1791.  
  1792.  
  1793. IO REQUEST RESULT
  1794.        io_Error        0 for success, or an error code as defined in
  1795.                        <ahi/devices.h> and <exec/errors.h>.
  1796.        io_Actual       If io_Error is 0, number of requests actually
  1797.                        flushed.
  1798.  
  1799.        The other fields, except io_Device, io_Unit and io_Command, are
  1800.        trashed.
  1801.  
  1802.  
  1803. EXAMPLE
  1804.  
  1805.  
  1806. NOTES
  1807.        This command affects ALL writes, even those sent by other
  1808.        applications. Make sure the code between CMD_STOP and CMD_START
  1809.        runs as fast as possible!
  1810.  
  1811.        Unlike most (all?) other devices, CMD_STOP and CMD_START do nest in
  1812.        ahi.device.
  1813.  
  1814.  
  1815. BUGS
  1816.  
  1817.  
  1818. SEE ALSO
  1819.        CMD_START, <ahi/devices.h>, <exec/errors.h>
  1820.  
  1821.  
  1822. ahi.device/CMD_WRITE
  1823.  
  1824. NAME
  1825.        CMD_WRITE -- Write raw samples to audio output (V4)
  1826.  
  1827.  
  1828. FUNCTION
  1829.        Plays the samples to the users prefered audio output.
  1830.  
  1831.  
  1832. IO REQUEST INPUT
  1833.        io_Device       Preset by the call to OpenDevice().
  1834.        io_Unit         Preset by the call to OpenDevice().
  1835.        io_Command      CMD_WRITE
  1836.        io_Data         Pointer to the buffer of samples to be played.
  1837.        io_Length       Number of bytes to play, must be a multiple of the
  1838.                        sample frame size (see ahir_Type).
  1839.        io_Offset       Must be 0.
  1840.        ahir_Type       The desired sample format, see <ahi/devices.h>.
  1841.        ahir_Frequency  The desired sample frequency in Hertz.
  1842.        ahir_Volume     The desired volume. The range is 0 to 0x10000, where
  1843.                        0 means muted and 0x10000 (== 1.0) means full volume.
  1844.        ahir_Position   Defines the stereo balance. 0 is far left, 0x8000 is
  1845.                        center and 0x10000 is far right.
  1846.        ahir_Link       If non-zero, pointer to a previously sent AHIRequest
  1847.                        which this AHIRequest will be linked to. This
  1848.                        request will be delayed until the old one is
  1849.                        finished (used for double buffering). Must be set
  1850.                        to NULL if not used.
  1851.  
  1852.  
  1853. IO REQUEST RESULT
  1854.        io_Error        0 for success, or an error code as defined in
  1855.                        <ahi/devices.h> and <exec/errors.h>.
  1856.        io_Actual       If io_Error is 0, number of bytes actually
  1857.                        played.
  1858.  
  1859.        The other fields, except io_Device, io_Unit and io_Command, are
  1860.        trashed.
  1861.  
  1862.  
  1863. EXAMPLE
  1864.  
  1865.  
  1866. NOTES
  1867.  
  1868.  
  1869. BUGS
  1870.        32 bit samples are not allowed yet.
  1871.  
  1872.  
  1873. SEE ALSO
  1874.        <ahi/devices.h>, <exec/errors.h>
  1875.  
  1876.  
  1877. ahi.device/CloseDevice
  1878.  
  1879. NAME
  1880.        CloseDevice -- Close the device
  1881.  
  1882.  
  1883. SYNOPSIS
  1884.        CloseDevice(ioRequest)
  1885.                    A1
  1886.  
  1887.        void CloseDevice(struct IORequest *);
  1888.  
  1889.  
  1890. FUNCTION
  1891.        This is an exec call that closes the device. Every OpenDevice()
  1892.        must be matched with a call to CloseDevice().
  1893.  
  1894.        The user must ensure that all outstanding IO Requests have been
  1895.        returned before closing the device.
  1896.  
  1897.  
  1898. INPUTS
  1899.        ioRequest - a pointer to the same struct AHIRequest that was used
  1900.            to open the device.
  1901.  
  1902.  
  1903. RESULT
  1904.  
  1905.  
  1906. EXAMPLE
  1907.  
  1908.  
  1909. NOTES
  1910.  
  1911.  
  1912. BUGS
  1913.  
  1914.  
  1915. SEE ALSO
  1916.       OpenDevice(), exec.library/CloseDevice()
  1917.  
  1918.  
  1919. ahi.device/NSCMD_DEVICEQUERY
  1920.  
  1921. NAME
  1922.        NSCMD_DEVICEQUERY -- Query the device for its capabilities (V4)
  1923.  
  1924.  
  1925. FUNCTION
  1926.        Fills an initialized NSDeviceQueryResult structure with
  1927.        information about the device.
  1928.  
  1929.  
  1930. IO REQUEST INPUT
  1931.        io_Device       Preset by the call to OpenDevice().
  1932.        io_Unit         Preset by the call to OpenDevice().
  1933.        io_Command      NSCMD_DEVICEQUERY
  1934.        io_Data         Pointer to the NSDeviceQueryResult structure,
  1935.                        initialized as follows:
  1936.                            DevQueryFormat - Set to 0
  1937.                            SizeAvailable  - Must be cleared.
  1938.                        It is probably good manners to clear all other
  1939.                        fields as well.
  1940.        io_Length       Size of the NSDeviceQueryResult structure.
  1941.  
  1942.  
  1943. IO REQUEST RESULT
  1944.        io_Error        0 for success, or an error code as defined in
  1945.                        <ahi/devices.h> and <exec/errors.h>.
  1946.        io_Actual       If io_Error is 0, the value in
  1947.                        NSDeviceQueryResult.SizeAvailable.
  1948.  
  1949.        The NSDeviceQueryResult structure now contains valid information.
  1950.  
  1951.        The other fields, except io_Device, io_Unit and io_Command, are
  1952.        trashed.
  1953.  
  1954.  
  1955. EXAMPLE
  1956.  
  1957.  
  1958. NOTES
  1959.  
  1960.  
  1961. BUGS
  1962.  
  1963.  
  1964. SEE ALSO
  1965.        <ahi/devices.h>, <exec/errors.h>
  1966.  
  1967.  
  1968. ahi.device/OpenDevice
  1969.  
  1970. NAME
  1971.        OpenDevice -- Open the device
  1972.  
  1973.  
  1974. SYNOPSIS
  1975.        error = OpenDevice(AHINAME, unit, ioRequest, flags)
  1976.        D0                 A0       D0    A1         D1
  1977.  
  1978.        BYTE OpenDevice(STRPTR, ULONG, struct AHIRequest *, ULONG);
  1979.  
  1980.  
  1981. FUNCTION
  1982.        This is an exec call.  Exec will search for the ahi.device, and
  1983.        if found, will pass this call on to the device.
  1984.  
  1985.  
  1986. INPUTS
  1987.        AHINAME - pointer to the string "ahi.device".
  1988.        unit - Either AHI_DEFAULT_UNIT (0), AHI_NO_UNIT (255) or any other
  1989.            unit the user has requested, for example with a UNIT tooltype.
  1990.            AHI_NO_UNIT should be used when you're using the low-level
  1991.            API.
  1992.        ioRequest - a pointer to a struct AHIRequest, initialized by
  1993.            exec.library/CreateIORequest(). ahir_Version *must* be preset
  1994.            to the version you need!
  1995.        flags - There is only one flag defined, AHIDF_NOMODESCAN, which
  1996.            asks ahi.device not to build the audio mode database if not
  1997.            already initialized. It should not be used by applications
  1998.            without good reasons (AddAudioModes uses this flag).
  1999.  
  2000.  
  2001. RESULT
  2002.        error - Same as io_Error.
  2003.        io_Error - If the call succeeded, io_Error will be 0, else
  2004.            an error code as defined in <exec/errors.h> and
  2005.            <devices/ahi.h>.
  2006.        io_Device - A pointer to the device base, which can be used
  2007.            to call the functions the device provides.
  2008.  
  2009.  
  2010. EXAMPLE
  2011.  
  2012.  
  2013. NOTES
  2014.  
  2015.  
  2016. BUGS
  2017.  
  2018.  
  2019. SEE ALSO
  2020.       CloseDevice(), exec.library/OpenDevice(), <exec/errors.h>,
  2021.       <devices/ahi.h>.
  2022.  
  2023.  
  2024.